SHELLME.TXT
===========

This directory contains one or more Aztec C65 programs written by me (Bill
Buckels) for the DOS 3.3 Aztec C Unix-like SHELL.

In order to use the DOS 3.3 Shell you will probably need to know some
commands. While this earlier shell is not as robust as the later Aztec C
ProDOS Shell it really is a pretty neat piece of work for its day.

Just don't go looking for wildcards or command line history. Wildcards came
later. If you use the AppleWin emulator you can paste in commands from the
Windows Clipboard using the SHIFT+INSERT key combination (disable your
Joysticks first). No history though!

For other platforms, I cannot speak.

Attribution
===========

This document is excerpted from AztecC_minimanual.txt which was 
produced by Rubywand (Jeff Hurlbert). Despite the fact that I plagiarize 
Jeff's stuff shamelessly I can take no credit for his large body of work
on behalf of the Apple II community.

In fact without Jeff's work in documenting the Apple II and the contribution
of his cohorts from csa2 I could take little credit for my own work on the
subject.

Bill Buckels, 2013

Introduction
============

Target: Manx Aztec C SHELL Version 2.4 for Apple II DOS 3.3
Compiler: C II Vers. 1.05h 6502 (C) 1982, 1983 by Manx Software Systems

DOS 3.3 SHELL General Use
=========================

The following is a list of the built-in functions available with the SHELL.
If a file has the same name as one of these functions, the SHELL will not
execute that file, but will execute the built-in function instead.

boot    cp           mv
bye     load         rm
call    lock         run
cat     ls           save
cd/ce   max files    unlock

These commands are all specified using lower case. 

Binary programs which are normally run using the DOS 'BRUN' command can be
loaded and executed by simply typing the name of the file followed by a
carriage return. The SHELL 'load' command can be used to load the image into
a different section of memory much the same as the DOS 'BLOAD' command.

Text file scripts containing a series of command lines can be executed by
typing the name of the text file followed by a carriage return. All SHELL
input is then taken from that file until the end is reached.

Some built-in SHELL utilities as well as binary programs produced using the
Aztec C compiler system require or allow arguments to be specified when the
command is executed These arguments are placed on the same line as the
command name separated by spaces. 

The SHELL has the ability to redirect the standard input and/or output of a
program to a file or a device. Normally the standard input and output of a
program are connected to the keyboard and screen respectively. The user may
redirect either or both of these connections to a file or a device such as a
printer. This is accomplished by using the special character '<' for input
and '>' for output.

Built-in Commands
=================

All built-in commands are specified as lower case. 

In the following discussions, the concept of current data drive and current
execution drive are used. Under DOS 3.3 the last drive accessed is
considered the current drive. Under the SHELL, the current data slot, drive
and volume must be explicitly changed by the user using the "cd" command At
any point where an optional slot, drive or volume parameter may be given, if
any are not specified, they will default to the current data value
respectively.

In general, all arguments to SHELL commands and to utility programs are
separated by blanks. Arguments in square brackets are optional and most
commands allow more than one file name per command line. In the following
descriptions, any reference to a file name is assumed to include the
optional slot, drive and volume parameters.

2.6.1 boot

boot n
Does a jump to address $Cn00. (Usually to reboot.) Example:

boot 6

Causes the floppy disk to reboot

2.6.2 bye

bye

Does a jump to the Apple machine language monitor at location $FF65. Reentry
to the SHELL is through $3D0 or by hitting RESET on systems with the
autostart ROM.

2.6.3 call

call addr

Performs a "jsr" to the address given. If addr is preceded by a '$', it is
interpreted as hex, otherwise as decimal.

2.6.4 cat

cat [file1] [file2] ...

Concatenates the named files to the standard output if no files are
specified. input is taken from the standard input. Examples:

cat test1 test2,d1
cat test1 test2,d1 > test3
cat > pr:
cat kb: > pr:

The first example displays "test1" from the current data drive on the screen
immediately followed by the file "test2" located on drive one. The second
example creates a new file called "test3" containing the two files "test1"
and "test2". The third example reads a character from the standard input and
writes it to the device "pr:" which is the printer. The fourth example is
equivalent to the third.

2.6.5 at

cd sn,dn,vn

Change the current data slot. drive and/or volume. Any or all of the three
parameters may be changed Those not specified will remain the same. If a
volume number is specified. it will be checked whenever a file is opened. A
volume number of zero, however, will match any disk. Examples:

cd s6,d1,v0
cd d2

The first example changes the current data disk to be slot six, drive one,
and any volume. The second example changes from whatever the current drive
was to drive two. The slot and volume remain the same.

2.6.6 ce

ce sn,dn,vn

Change the current execution slot, drive and/or volume. Execution parameters
are used when loading and running a particular binary program or SHELL file.
If the name includes a specific reference to a slot, drive or volume, that
parameter is used If there is no reference as to which device holds the
file, the current data disk is searched and if the file is not found there,
then the current execution disk is checked This allows all utility programs
to reside on a different disk than the one being actively used.

ce s6,d2,v0
ce d1

The first example changes the current execution disk to be slot six, drive
two, and any volume. The second example changes from whatever the current
drive was to drive one. The slot and volume remain the same.

2.6.7 cp

cp file1 file2

Copies files from the specified device to file2. Note that file2 will be
overwritten if it already exists. Examples:

cp test oldtest
cp test,d1 test

The first example makes a copy of "test" on the same disk called "oldtest".
The second example assumes that drive one is not the current data drive and
copies the file "test" from drive one to the current drive.

2.6.8 load

load file [aN] [lN]

Loads a binary file into memory. If the starting address and/or length are
not specified, they are taken from the first two words of the file. After
loading, the start address and length are displayed on the screen. These
values are remembered for use in the save and run commands. If N begins with
a '$', the value is interpreted as a hex value otherwise as decimal.
Examples:

load tabset
A=0800 L=12F2

load tabset a$2000
A=2000 L=12F2

The first example loads the tabset program into memory. The shell displays
the load address and length. The second example loads the tabset program
into memory at address hex 2000.

2.6.9 lock

lock file 1 [file2] ...

Lock the file on the specified slot, drive and volume. If any of slot, drive
or volume are not given, they default to the current data values. Examples:

lock test1
lock tcst1 test2 test3,d2

The first example locks file test1 on the current data disk. Example two
locks files test1 and test2 on the current data disk and locks file test3 on
drive two of the current data slot and volume.

2.6.10 ls

ls [sn,dn,vn] ...

Perform the catalog function on the specified slot, drive and volume. This
command defaults to the current data slot, drive and volume. If more than
one is specified, they will be cataloged in order. The SHELL will wait for a
key to be pressed between different catalogs. Unfortunately, the output of
ls cannot be redirected. Examples:

ls
ls d1 d2

The first example does a catalog of the current data slot. drive and volume.
The second example catalogs drive one and then drive two of the current data
slot and volume.

2.6.11 maxfiles

maxfiles n

Allocates n buffers for open files. This command is similar to the DOS
'MAXFILES' command. It specifies the maximum number of disk files which may
be open at anyone time. When the SHELL is initialized, the value is
defaulted to 3. Example:

maxfiles 4

For an application which will have four disk files open, maxfiles is set to
four.

2.6.12 mv

mv [-f] file1 file2

Moves file1 to file2. If the slot, drive, and volume of file1 are the same
as that of file2, file1 is simply renamed as file2. If they are different,
file1 is copied to file2 on the specified device and file1 is deleted. If
file2 exists, an error message will be printed. If the '-f' option is given,
no error message will be given and file2 will be removed first. Examples:

mv test foo
mv -f test foo
mv test test,d2

The first example renames the file "test" as "foo". The second example
deletes the file "foo" and then renames "test". The last example copies the
file "test" from the current data drive to drive two and then deletes "test"
from the current drive.

2.6.13 rm

rm file1 [file2] ...

Delete the specified file or files. If a file is locked, a message is
displayed giving the name of the file which is locked. Examples:

rm file1 file2
rm foo,s5

The first example deletes files "file1" and "file2" from the current data
drive. The second example deletes the file "foo" from the disk in slot five.
The drive number will be the same as the current data drive number.

2.6.14 run

run [argl] [arg2] ...

Does a jsr to the starting address of the last file loaded after pushing a
pointer to the argument vector and the number of arguments on the stack.
Argv[0] will be the "run" string. Example:

load tabset
A=0800 L=12F0
run 8

This example loads the program "tabset" into memory. The SHELL displays the
load address and length. The "run" command then calls hex 800 ($800) with
the argument "8". The three lines are equivalent to typing "tabset 8" all by
itself.

2.6.15 save

save file [aN] [lN]

Saves a part of memory to a file on the specified device. If the starting
address and length are not specified, the starting address and length of the
last file "load"ed will be used if N is begun with a '$', the value is
interpreted as a hex value otherwise as decimal. Examples:

save foo
save foo a$800 l1000

The first example will save in a file called "foo", whatever the last
program loaded or run. The second example will save a thousand bytes of
memory starting at hex 800 in a file called "foo".

2.6.16 unlock

unlock file1 [file2] ...

Unlock the file on the specified Slot, drive and volume. If any of Slot,
drive or volume are not given, they default to the current data values.
Examples:

unlock test1
unlock test1 test2 test3,d2

The first example unlocks file test1 on the current data disk. Example two
unlocks files test1 and test2 on the current data disk and unlocks file
test3 on drive two of the current data slot and volume.

2.7 Batch Facilities (Text file scripts)

Text files containing a series of SHELL command lines can be executed by
typing the name of the text file followed by a carriage return. Note that
the type of the file must be 'T'. All SHELL input is then taken from that
file until the end is reached. SHELL command files may not be nested, but
they may be chained. If a SHELL command line executes a second SHELL command
file, the first command file is closed and forgotten. Lines beginning with
the '#' character are ignored by the shell and can be used as comments.

When the SHELL is booted for the first time, the disk that the SHELL was
booted from is searched for a file called ".PROFILE". If this file is found
and is a text file, it will be executed immediately. This allows any special
startup procedures to be automatically initiated. SHELL command files may
also be given up to 9 arguments. These arguments are referenced by the
character '$' followed by the number of the argument to be used. Argument 0
is the name of the SHELL command file itself. For example, to link together
several files, the following one line SHELL command file might be created:

ln -o ln.out $1 $2 $3 $4 $5 $6 $7 $8 $9 sh65.lib

If the file was called "linkit", it could be used by typing:

linkit f1.rel f2.rel f3.rel

If an argument does not exist, it is ignored.

There are two special "built-in" commands that the SHELL will only recognize
when read from a SHELL command file. These commands are used for additional
control over the processing of the commands in a SHELL command file.

2.7.1 loop

loop

This command is used to start and end a loop in a SHELL command file. The
command lines between the two loop statements will be executed once for each
argument given to the SHELL command file. During the loop, two special
arguments are available for use. '$#' is replaced by the number of the
current argument being processed. The two-character sequence '$%' will be
replaced by the current argument itself. The following is an example of a
SHELL command file which will compile and assemble from one to nine files,
one at a time.

set -x -a
loop
# This is argument number $#, $%
c65 -a -o $%.asm $%.c
as65 -o $%.rel $%.asm
loop

If the preceding lines were placed in a file called "compile", then the
statement:

compile test junk foo

would compile and assemble the three files "test.c", "junk.c", and "foo.c"
into the corresponding ".rel" files and produce:

loop
This is argument 1, test
c65 -a -o test.asm test.c
as65 -o test.rel test.asm
loop
This is argument 2, junk
c65 -a -o junk.asm junk.c
as65 -o junk.rel junk.asm
loop
This is argument 3, foo
c65 -a -o foo.asm foo.c
as65 -o foo.rel foo.asm
loop

2.7.2 set

set [+-x] [+-a] [+-n]

Sets or clears one of three internal flags in the SHELL. Using '+' will
clear the flag while '-' will set it. The flags are defined as follows:

x  Echo command lines to the screen. Defaults to off.
a  Abort the SHELL command file if a command or program exits with a non-
   zero value. Defaults to no abort.
n  Parse the command lines, but do not execute them. Defaults to off.

Thus, to see each line being executed, the first line of a SHELL command
file should be:

set -x

To have a SHELL command file exit if an error occurs, include the line:

set -a

The "set" command may only be executed within a SHELL command file.

End of Document
===============

Have Fun!

Bill Buckels
bbuckels@mts.net
May 2013

http://www.aztecmuseum.ca

End of Document

